ASP.NET Core Web API 入門心得

TLDR

• ControllerBase 為 Web API 的基礎類別，若需支援 View 或 Filter 事件可改繼承 Controller。
• [ApiController] 可啟用屬性路由、HTTP 400 自動回應、參數繫結推斷等功能。
• 建議使用 ActionResult<T> 作為 Action 回傳型別，以兼顧資料回傳與狀態碼處理。
• 非同步方法建議以 Async 為後綴，並使用 Task<T> 作為回傳型別。
• Swagger 整合時，務必為每個 Action 明確標註 HTTP Attribute（如 [HttpGet]），否則可能導致 UI 呈現異常。
• 可透過 IOperationFilter 在 Swagger 中增加全域輸入欄位（如 Token）。
• 透過 GenerateDocumentationFile 與 IncludeXmlComments 可將 XML 註解自動整合至 Swagger 文件。

ControllerBase 與 ApiController

什麼情況下會遇到這個問題：當需要區分 MVC 與 Web API 的 Controller 行為，或希望簡化 API 的驗證邏輯時。

• ControllerBase：ASP.NET Core 中 Web API 預設繼承此類別。若需同時支援 View 或處理 OnActionExecuting 等 Filter 事件，可改繼承 Controller。
• ApiController：加上此 Attribute 可自動啟用屬性路由、HTTP 400 自動回應、繫結來源推斷等機制。
• 自訂父類別：若不想在每個 Controller 重複宣告，可定義 BasicController 繼承 ControllerBase 並加上 [ApiController]，再讓其他 Controller 繼承之。

若需停用 ApiController 的特定行為，可在 Program.cs 調整：

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options => {
        options.SuppressModelStateInvalidFilter = true; // 停用 HTTP 400 自動回應
        options.SuppressConsumesConstraintForFormFileParameters = true; // 停用表單資料推斷
        options.SuppressInferBindingSourcesForParameters = true; // 停用參數繫結推斷
        options.SuppressMapClientErrors = true; // 停用錯誤詳細資料
    });

路由設定與參數繫結

什麼情況下會遇到這個問題：當需要定義 RESTful 風格的 API 路由，或需要明確指定參數來源時。

• 路由優先權：由高至低為 Action > Controller > 父類別 Controller。
• HTTP 動詞：必須明確使用 [HttpGet]、[HttpPost] 等 Attribute，未設定時預設為 GET。
• 參數繫結推斷：
  • [FromBody]：處理複雜型別。
  • [FromForm]：處理 IFormFile。
  • [FromRoute]：處理路由參數。
  • [FromQuery]：處理查詢字串。

回傳型別與非同步處理

什麼情況下會遇到這個問題：當需要標準化 API 的回傳格式，並處理高併發請求時。

• 回傳型別建議：
  • 僅回傳狀態碼：使用 IActionResult。
  • 回傳資料與狀態碼：使用 ActionResult<T>。
• 非同步寫法：使用 async 修飾詞並回傳 Task<T>，Action 名稱建議以 Async 結尾。

[HttpGet("{id}")]
public async Task<ActionResult<string>> GetByIdAsync(int id) {
    var result = await _service.GetByIdAsync(id);
    return Ok(result);
}

Swagger 文件整合

什麼情況下會遇到這個問題：當需要為 API 產生互動式文件，或需要自訂 API 說明與欄位時。

• 基本設定：勾選「啟用 OpenAPI 支援」後，透過 AddSwaggerGen() 與 UseSwaggerUI() 啟用。
• 注意事項：若 Action 缺乏 HTTP Attribute，Swagger 可能無法正確解析，應避免設計非 Action 的 public 方法。
• 擴充功能：
  • 自訂輸入欄位：實作 IOperationFilter 介面並在 AddSwaggerGen 中註冊。
  • XML 註解整合：
    1. 在 .csproj 設定 <GenerateDocumentationFile>true</GenerateDocumentationFile>。
    2. 在 Program.cs 使用 opt.IncludeXmlComments() 載入 XML 檔案。
    3. 在 Action 或 Model 上方加入 /// <summary> 註解，即可自動顯示於 Swagger UI。

---

異動歷程

• 2023-08-04 初版文件建立。